/**
* @file DSMInterface.h
* Common defines and typedefs used for accessing DSM for TWAIN Applications.
* @author TWAIN Working Group
* @date April 2007
*/

#ifndef __DSM_H__
#define __DSM_H__

#pragma once


#include "twain.h"


bool loadDSMLibrary();
void unloadDSMLibrary();

/**
* Initialize and register the entry point into the DSM.
* @param[in] _pOrigin Identifies the source module of the message. This could
*           identify an Application, a Source, or the Source Manager.
*
* @param[in] _pDest Identifies the destination module for the message.
*           This could identify an application or a data source.
*           If this is NULL, the message goes to the Source Manager.
*
* @param[in] _DG The Data Group. 
*           Example: DG_IMAGE.
*
* @param[in] _DAT The Data Attribute Type.
*           Example: DAT_IMAGEMEMXFER.
*    
* @param[in] _MSG The message.  Messages are interpreted by the destination module
*           with respect to the Data Group and the Data Attribute Type.  
*           Example: MSG_GET.
*
* @param[in,out] _pData A pointer to the data structure or variable identified 
*           by the Data Attribute Type.
*           Example: (TW_MEMREF)&ImageMemXfer
*                   where ImageMemXfer is a TW_IMAGEMEMXFER structure.
*                    
* @return a valid TWRC_xxxx return code.
*          Example: TWRC_SUCCESS.
*/
TW_UINT16 _DSM_Entry( pTW_IDENTITY pOrigin, pTW_IDENTITY pDest, TW_UINT32 DG, TW_UINT16 DAT, TW_UINT16 MSG, TW_MEMREF pData );

/**
* Allocate global memory
* @param[in] _size of memory to allocate.
* @return TW_HANDLE to the memory allocated.
*/
TW_HANDLE _DSM_Alloc( TW_UINT32 _size );

/**
* Free previously allocated global memory
* @param[in] _hMemory TW_HANDLE to the memory needing free.
*/
void _DSM_Free( TW_HANDLE _hMemory );

/**
* Lock global memory from being updated by others. return a pointer to the 
* memory so we can update it.
* @param[in] _hMemory TW_HANDLE to the memory to update.
* @return TW_MEMREF pointer to the memory.
*/
TW_MEMREF _DSM_LockMemory( TW_HANDLE _hMemory );

/**
* Unlock global memory after locking. to allow updating by others.
* @param[in] _hMemory TW_HANDLE to memory returned by _DSM_Alloc
*/
void _DSM_UnlockMemory( TW_HANDLE _hMemory );

/**
* Not Used.
* @todo Not Implimented
* @param[in] twEvent reference to the TW_EVENT
* @return TW_UINT16
*/
TW_UINT16 HandleEvent( TW_EVENT &twEvent );

#endif // __DSM_H__
